java 开发日志规范

一. 日志

日志的作用：记录用户操作、系统运行状态，好的日志输出可以帮助研发和运维快速的定位问题以及系统瓶颈

二. 日志级别

常见的日志级别有5种，分别是DEBUG，INFO，WARN，ERROR，FATAL，日常开发中，我们需要选择合适的日志级别

DEBUG：调试问题使用，日常开发记得一定要打印出输入、输出、关键逻辑里面的运行时数据;
INFO：打印程序运行信息，启动信息等
WARN：警告日志，打印一些警告信息，比如参数校验错误等等，需要开发关注；
ERROR：打印程序错误信息，对正常业务有影响，需要监控的，必须要打印上下文信息，方便查找问题
FATAL：重大灾难信息，比如数据库无法连接等需要立即处理的问题

三. 统一日志管理

使用统一日志管理平台组件

四. 日志打印规范

开发过程中，应遵循以下日志打印规范

1. 打印出方法的入参、出参

原则：不需要打印很多日志，只需要打印可以快速定位问题的有效日志。

如：方法进来的时候，打印入参，在方法返回的时候，就是打印出参，返回值。

2. 选择合适的日志格式

日志格式，应当包含以下基本的信息：如当前时间戳（一般毫秒精确度）、日志级别，线程名字等等，

举例：

1
2
3

<encoder>
  <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{EagleEye-TraceID}] [%thread] %-5level %logger{36}- %msg%n</pattern>
</encoder>

3. if…else…或switch等条件时，每个分支首行都尽量打印日志

if…else…或者switch这样的条件判断，可以在分支的首行打印日志，这样排查问题时，就可以通过日志，确定进入了哪个分支，代码逻辑更清晰，也更方便排查问题了。

4.日志级别比较低时，进行日志开关判断

对于trace/debug这些比较低的日志级别，必须进行日志级别的开关判断。

例：

User user = new User(10000L, "hello树", "男");
if (log.isDebugEnabled()) {
    log.debug("userId is: {}", user.getId());
}

因为当前有如下的日志代码：

1	logger.debug("Processing trade with id: " + id + " and symbol: " + symbol);

如果配置的日志级别是warn的话，上述日志不会打印，但是会执行字符串拼接操作，如果symbol是对象，还会执行toString()方法，浪费了系统资源，执行了上述操作，最终日志却没有打印，因此建议加日志开关判断。

5. 不能直接使用日志系统（Log4j、Logback）中的 API，而是使用日志框架SLF4J中的API，推荐使用Lombok提供的快速日志记录方式，日志打印统一使用Lombok

SLF4J 是门面模式的日志框架，有利于维护和各个类的日志处理方式统一，并且可以在保证不修改代码的情况下，很方便的实现底层日志框架的更换，建议直接类添加@Slf4j注解，直接使用log调用对应级别的方法即可

如：

1
2
3

@Slf4j
@Service
public class UscApiServiceImpl implements UscApiService

6. 建议使用参数占位{}，而不是用+拼接。

反例：

1	LOGGER.info("Processing trade with id: " + id + " and symbol: " + symbol);

上面的例子中，使用+操作符进行字符串的拼接，有一定的性能损耗。

正例:

1	log.info("UserApiServiceImpl \| queryRateByPayType \| payType:{}",payType);

使用了大括号{}来作为日志中的占位符，比于使用+操作符，更加优雅简洁。并且，相对于反例，使用占位符仅是替换动作，可以提升性能。

开发环境、测试环境日志级别可以根据需要配置成info或debug级别，线上环境需要配置成info级别。

7. 使用异步的方式来输出日志。

日志最终会输出到文件或者其它输出流中的，IO性能会有要求的。如果异步，就可以显著提升IO性能。
使用异步的方式来输出日志。以logback为例，要配置异步，使用AsyncAppender

1
2
3

<appender name="FILE_ASYNC" class="ch.qos.logback.classic.AsyncAppender">
    <appender-ref ref="ASYNC"/>
</appender>

8. 不要使用e.printStackTrace()

反例：

try{
  // 业务代码处理
}catch(Exception e){
  e.printStackTrace();
}

正例：

try{
  // 业务代码处理
}catch(Exception e){
  log.error("程序有异常啦",e);
}

理由：

e.printStackTrace()打印出的堆栈日志跟业务代码日志是交错混合在一起的，通常排查异常日志不太方便。
e.printStackTrace()语句产生的字符串记录的是堆栈信息，如果信息太长太多，字符串常量池所在的内存块没有空间了。

9. 异常日志不要只打一半，要输出全部错误信息,日志打印时要将敏感字段脱敏或加密

反例1：

try {
    //业务代码处理
} catch (Exception e) {
    // 错误
    LOG.error('程序有异常啦');
}

异常e都没有打印出来，所以压根不知道出了什么类型的异常。

反例2：

try {
    //业务代码处理
} catch (Exception e) {
    // 错误
    LOG.error('你的程序有异常啦', e.getMessage());
}

e.getMessage()不会记录详细的堆栈异常信息，只会记录错误基本描述信息，不利于排查问题。

正例：

try {
    //业务代码处理
} catch (Exception e) {
    // 错误
    LOG.error('你的程序有异常啦', e);
}

10. 禁止在线上环境开启 debug

禁止在线上环境开启debug。

因为一般系统的debug日志会很多，并且各种框架中也大量使用 debug的日志，线上开启debug相当占用磁盘资源，影响业务系统的正常运行。

11.不要记录了异常，又抛出异常

反例如下：

1 2	log.error("IO exception", e); throw new MyException(e);

这样实现的话，通常会把栈信息打印两次。这是因为捕获了MyException异常的地方，还会再打印一次。
这样的日志记录，或者包装后再抛出去，不要同时使用！否则你的日志看起来会让人很迷惑。

12.避免重复打印日志

避免重复打印日志，如果已经有一行日志清楚表达了意思，避免再冗余打印

if(user.isVip()){
  log.info("该用户是会员,Id:{}",user,getUserId());
  //冗余，可以跟前面的日志合并一起
  log.info("开始处理会员逻辑,id:{}",user,getUserId());
  //会员逻辑
}else{
  //非会员逻辑
}

13.日志文件分离

可以把不同类型的日志分离出去，比如access.log，或者error级别error.log，都可以单独打印到一个文件里面。

1	如：将不同级别的日志分别打印到不同的日志文件中${log.moduleName}-error.log、${log.moduleName}-warn.log、${log.moduleName}-info.log、${log.moduleName}-debug.log等

也可以根据不同的业务模块，打印到不同的日志文件里，这样我们排查问题和做数据统计的时候，都会比较方便。

14. 核心功能模块，建议打印较完整的日志

日常开发中，如果核心或者逻辑复杂的代码，建议添加详细的注释，以及较详细的日志。
多详细？如果你的核心程序哪一步出错了，通过日志可以定位到，那就可以。

15. 系统对外的接口,或者调用其他系统的接口入参、出参必须打印出来，日志级别为info

1	log.info("RPC \| snt-upc \| AppPayApiService \| queryPayResult \| start \| appPayQueryDTO:{}", JSON.toJSONString(appPayQueryDTO));

java 日志规范